homework 4, version 1

Submission by: Ayush Goel (ayush@mit.edu)

Homework 4: Epidemic modeling I

18.S191, fall 2020

This notebook contains built-in, live answer checks! In some exercises you will see a coloured box, which runs a test case on your code, and provides feedback based on the result. Simply edit the code, run it, and the check runs again.

For MIT students: there will also be some additional (secret) test cases that will be run as part of the grading process, and we will look at your notebook and write comments.

Feel free to ask questions!

Let's create a package environment:

Exercise 1: Modelling recovery

In this exercise we will investigate a simple stochastic (probabilistic) model of recovery from an infection and the time $\tau$ needed to recover. Although this model can be easily studied analytically using probability theory, we will instead use computational methods. (If you know about this distribution already, try to ignore what you know about it!)

In this model, an individual who is infected has a constant probability $p$ to recover each day. If they recover on day $n$ then $\tau$ takes the value $n$. Each time we run a new experiment $\tau$ will take on different values, so $\tau$ is a (discrete) random variable. We thus need to study statistical properties of $\tau$, such as its mean and its probability distribution.

Exercise 1.1 - Probability distributions

👉 Define the function bernoulli(p), which returns true with probability $p$ and false with probability $(1-p)$.

👉 Write a function recovery_time(p) that returns the time taken until the person recovers.

We should always be aware of special cases (sometimes called "boundary conditions"). Make sure not to run the code with $p=0$! What would happen in that case? Your code should check for this and throw an ArgumentError as follows:

throw(ArgumentError("..."))  

with a suitable error message.

👉 What happens for $p=1$?

Exercise 1.2

👉 Write a function do_experiment(p, N) that runs the function recovery_time N times and collects the results into a vector.

Exercise 1.3

👉 Write a function frequencies(data) that calculates and returns the frequencies (i.e. probability distribution) of input data.

The input will be an array of integers, with duplicates, and the result will be a dictionary that maps each occured value to its frequency in the data.

For example,

frequencies([7, 8, 9, 7])

should give

Dict(
    7 => 0.5, 
    8 => 0.25, 
    9 => 0.25
)

As with any probability distribution, it should be normalised to $1$, in the sense that the total probability should be $1$.

Let's run an experiment with $p=0.25$ and $N=10,000$.

The frequencies dictionary is difficult to interpret on its own, so instead, we will plot it, i.e. plot $P(\tau =n)$ against $n$, where $n$ is the recovery time.

Plots.jl comes with a function bar, which does exactly what we want:

Great! Feel free to experiment with this function, try giving it a different array as argument. Plots.jl is pretty clever, it even works with an array of strings!

Exercise 1.4

Next, we want to add a new element to our plot: a vertical line. To demonstrate how this works, here we added a vertical line at the maximum value.

To write this function, we first create a base plot, we then modify that plot to add the vertical line, and finally, we return the plot. More on this in the next info box.

Note about plotting

Plots.jl has an interesting property: a plot is an object, not an action. Functions like plot, bar, histogram don't draw anything on your screen - they just return a Plots.Plot. This is a struct that contains the description of a plot (what data should be plotted in what way?), not the picture.

So a Pluto cell with a single line, plot(1:10), will show a plot, because the result of the function plot is a Plot object, and Pluto just shows the result of a cell.

Modifying plots

Nice plots are often formed by overlaying multiple plots. In Plots.jl, this is done using the modifying functions: plot!, bar!, vline!, etc. These take an extra (first) argument: a previous plot to modify.

For example, to plot the sin, cos and tan functions in the same view, we do:

function sin_cos_plot()
    T = -1.0:0.01:1.0
    
    result = plot(T, sin.(T))
    plot!(result, T, cos.(T))
    plot!(result, T, tan.(T))

    return result
end

💡 This example demonstrates a useful pattern to combine plots:

1. Create a new plot and store it in a variable

2. Modify that plot to add more elements

3. Return the plot

It is recommended that these 3 steps happen within a single cell. This can prevent some strange glitches when re-running cells. There are three ways to group expressions together into a single cell: begin, let and function. More on this later!

👉 Write the function frequencies_plot_with_mean that calculates the mean recovery time and displays it using a vertical line.

👉 Write an interactive visualization that draws the histogram and mean for $p$ between $0.01$ (not $0$!) and $1$, and $N$ between $1$ and $100,000$, say. To avoid a naming conflict, call them p_interactive and N_interactive, instead of just p and N.

As you separately vary $p$ and $N$, what do you observe about the mean in each case? Does that make sense?

Exercise 1.5

👉 What shape does the distribution seem to have? Can you verify that by adding a second plot with the expected shape?

Exercise 1.6

👉 Use $N=10,000$ to calculate the mean time $⟨\tau (p)⟩$ to recover as a function of $p$ between $0.001$ and $1$ (say). Plot this relationship.

Exercise 2: Agent-based model for an epidemic outbreak – types

In this and the following exercises we will develop a simple stochastic model for combined infection and recovery in a population, which may exhibit an epidemic outbreak (i.e. a large spike in the number of infectious people). The population is well mixed, i.e. everyone is in contact with everyone else. [An example of this would be a small school or university in which people are constantly moving around and interacting with each other.]

The model is an individual-based or agent-based model: we explicitly keep track of each individual, or agent, in the population and their infection status. For the moment we will not keep track of their position in space; we will just assume that there is some mechanism, not included in the model, by which they interact with other individuals.

Exercise 2.1

Each agent will have its own internal state, modelling its infection status, namely "susceptible", "infectious" or "recovered". We would like to code these as values S, I and R, respectively. One way to do this is using an enumerated type or enum. Variables of this type can take only a pre-defined set of values; the Julia syntax is as follows:

We have just defined a new type InfectionStatus, as well as names S, I and R that are the (only) possible values that a variable of this type can take.

👉 Define a variable test_status whose value is S.

👉 Use the typeof function to find the type of test_status.

👉 Convert x to an integer using the Integer function. What value does it have? What values do I and R have?

Exercise 2.2

For each agent we want to keep track of its infection status and the number of other agents that it infects during the simulation. A good solution for this is to define a new type Agent to hold all of the information for one agent, as follows:

When you define a new type like this, Julia automatically defines one or more constructors, which are methods of a generic function with the same name as the type. These are used to create objects of that type.

👉 Use the methods function to check how many constructors are pre-defined for the Agent type.

👉 Create an agent test_agent with status S and num_infected equal to 0.

👉 For convenience, define a new constructor (i.e. a new method for the function) that takes no arguments and creates an Agent with status S and number infected 0, by calling one of the default constructors that Julia creates. This new method lives outside (not inside) the definition of the struct. (It is called an outer constructor.)

(In Pluto, multiple methods for the same function need to be combined in a single cell using a begin end block.)

Let's check that the new method works correctly. How many methods does the constructor have now?

Exercise 2.3

👉 Write functions set_status!(a) and set_num_infected!(a) which modify the respective fields of an Agent. Check that they work. [Note the bang ("!") at the end of the function names to signify that these functions modify their argument.]

👉 We will also need functions is_susceptible and is_infected that check if a given agent is in those respective states.

Exericse 2.4

👉 Write a function generate_agents(N) that returns a vector of N freshly created Agents. They should all be initially susceptible, except one, chosen at random (i.e. uniformly), who is infectious.

We will also need types representing different infections.

Let's define an (immutable) struct called InfectionRecovery with parameters p_infection and p_recovery. We will make it a subtype of an abstract AbstractInfection type, because we will define more infection types later.

Exercise 2.5

👉 Write a function interact! that takes an affected agent of type Agent, an source of type Agent and an infection of type InfectionRecovery. It implements a single (one-sided) interaction between two agents:

• If the agent is susceptible and the source is infectious, then the source infects our agent with the given infection probability. If the source successfully infects the other agent, then its num_infected record must be updated.

• If the agent is infected then it recovers with the relevant probability.

• Otherwise, nothing happens.

Play around with the test case below to test your function! Try changing the definitions of agent, source and infection. Since we are working with randomness, you might want to run the cell multiple times.

Exercise 3: Agent-based model for an epidemic outbreak – Monte Carlo simulation

In this exercise we will build on Exercise 2 to write a Monte Carlo simulation of how an infection propagates in a population.

Make sure to re-use the functions that we have already written, and introduce new ones if they are helpful! Short functions make it easier to understand what the function does and build up new functionality piece by piece.

You should not use any global variables inside the functions: Each function must accept as arguments all the information it requires to carry out its task. You need to think carefully about what the information each function requires.

Exercise 3.1

👉 Write a function step! that takes a vector of Agents and an infection of type InfectionRecovery. It implements a single step of the infection dynamics as follows:

• Choose two random agents: an agent and a source.

• Apply interact!(agent, source, infection).

• Return agents.

👉 Write a function sweep!. It runs step! $N$ times, where $N$ is the number of agents. Thus each agent acts, on average, once per sweep; a sweep is thus the unit of time in our Monte Carlo simulation.

👉 Write a function simulation that does the following:

1. Generate the $N$ agents.

2. Run sweep! a number $T$ of times. Calculate and store the total number of agents with each status at each step in variables S_counts, I_counts and R_counts.

3. Return the vectors S_counts, I_counts and R_counts in a named tuple, with keys S, I and R.

You've seen an example of named tuples before: the student variable at the top of the notebook!

Feel free to store the counts in a different way, as long as the return type is the same.

We used a let block in this cell to group multiple expressions together, but how is it different from begin or function?

function vs. begin vs. let

Writing functions is a way to group multiple expressions (i.e. lines of code) together into a mini-program. Note the following about functions:

• A function always returns one object.[1] This object can be given explicitly by writing return x, or implicitly: Julia functions always return the result of the last expression by default. So f(x) = x+2 is the same as f(x) = return x+2.

• Variables defined inside a function are not accessible outside the function. We say that function bodies have a local scope. This helps to keep your program easy to read and write: if you define a local variable, then you don't need to worry about it in the rest of the notebook.

There are two other ways to group epxressions together that you might have seen before: begin and let.

begin

begin will group expressions together, and it takes the value of its last subexpression.

We use it in this notebook when we want multiple expressions to always run together.

let

let also groups multiple expressions together into one, but variables defined inside of it are local: they don't affect code outside of the block. So like begin, it is just a block of code, but like function, it has a local variable scope.

We use it when we want to define some local (temporary) variables to produce a complicated result, without interfering with other cells. Pluto allows only one definition per global variable of the same name, but you can define local variables with the same names whenever you wish!

1

Even a function like

f(x) = return

returns one object: the object nothing — try it out!

Exercise 3.2

Alright! Every time that we run the simulation, we get slightly different results, because it is based on randomness. By running the simulation a number of times, you start to get an idea of the mean behaviour of our model. This is the essence of a Monte Carlo method! You use computer-generated randomness to generate samples.

Instead of pressing the button many times, let's have the computer repeat the simulation. In the next cells, we run your simulation num_simulations=20 times with $N=100$, $p_{\text{infection}}=0.02$, $p_{\text{infection}}=0.002$ and $T=1000$.

Every single simulation returns a named tuple with the status counts, so the result of multiple simulations will be an array of those. Have a look inside the result, simulations, and make sure that its structure is clear.